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Abstract 

This manual describes version 5.0 of Kraut, the debugging system lor Pcrq Pascal running on the Perq 
Systems PKRQ computer under the Accent operating system. Kraut provides most of the commands of 
traditional symbolic debuggers such as setting of breakpoints, state inspection/modification and source file 
access, it also contains MaC'H, a low icvel debugger for the inspection of ilic target process on the qcodc and 
microcode level. The novel feature of Kraut is Path Rules, a flexible debugging mechanism based on path 
expressions. 
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Chapter One 
Introduction 



KRAUT is a remote symbolic debugger for Pcrq Pascal running under the Accent operating system. One of 
the novel features of Kraut is that the user can specify the expected behaviour of a computation with path 
expressions. The debugger runs in its own address space and inspection and modification of the target 
process address space is done by means of Accent kernel calls. Currently both the debugger and the target 
process have to reside on the same Pcrq, but later it will be possible to debug processes which are located on 
a physically remote Pcrq. 

The manual is organized as follows: Section 1.1 explains how to retrieve the newest version of the debugger, 
how to generate symbolic information and how to invoke die debugger. Pascal's scope rules have been 
extended in Kraut and arc described in Section 2. The major design objective of Kraut was to test the 
viability of path expressions in the context of debugging. Path expressions are embedded in path rules 
which arc introduced in Section 3. In addition to path rule commands, Kraut provides traditional 
debugging commands for setting breakpoints, inspecting and modifying variables in the user process 
address space, opening source files and searching for text strings. The complete command language of 
Kraut is described in Section 4. Kraut contains the low level debugger Macf, which allows the 
inspection and modification of the target process on qcodc and (partially) on microcode level. Mack is 
intended mainly for compiler writers and microprogram mere and is described in Section 5. Kraut is still 
actively being developed and internal debugger errors might show up while you arc debugging your 
program. Section 6 shows you how to cope with these errors and Section 7 mentions the current restrictions 
and known bugs of the debugger. 



1.1 Getting Started 

If Kraut is not yet part of your Accent system or if you want to get a newer version, you have to retrieve it 
from the CFS Vax@CMU. KRAUT can be retrieved using the update program with the following 
command: 

update krautrun/test 

The run file is debugger . run and it has to reside in the partition <boot>. 

Symbolic information for a module is produced by the compiler if the module is compiled with the 
/scrounge switch. For example 
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compile test . pas/scrounge 

generates the symbolic information for tes t . pas. The scrounge switch is on by default. If you want to 
suppress the generation of the symbolic information use noscrounge. The symbolic information is 
contained in two files with the extension sym and qmap . Kraut must have access to these files to allow 
symbolic debugging at other than a routine and module name level. 

Kraut can be invoked in the following ways. 

1. It can be called on the shell level by closing the run command with the t character: for example 
RUN testt. This allows the definition of path rules, debugger variables and breakpoints before 
the execution of the program. 

2. lyping the Shell command DKBUG will suspend the execution of a running process. In this 
case the Spice Process Manager reports a Trap in the target process and invokes the 
debugger. This allows you to catch processes in dead loops or in I/O wait states. 

3. Any uncaught exception in the target process will invoke Kraut. 

4. Kraut can be invoked via Sapphire if the item Debug Process is selected from the Pop-Up 
Menu. The menu is displayed from a window or an icon in a manner that is consistent with 
regular Sappihrk window management. 

In all of die above methods of invoking Kraut, a bug symbol appears in the icon corresponding to the 
window running the process in question. The Sappiiiri- cursor appears on the screen and prompts for the 
creation of a Debug Window. 

Kraut tries to set the current directory to the directory where the main program was compiled. If that 
directory docs not exist, a warning is given and the current directory is left as <current>. 

Kraut does a consistency check between symbolic information and object files: if a symbol table was not 
produced at the same time as the object file or if the source file is younger than the scg file a warning is 
issued. In this case the debugger should be used with caution, because any information from those modules 
could be wrong. Any information retrieved from inconsistent symbol tables is marked with a '?'. 

Kraut has a transcript facility to document errors that cannot be reproduced and bugs in modules not 
written by yourself. If you encounter a bug you cannot cope with, you might want to send the transcript file 
to the maintainor of the module (sec MAINTAINKR and REPORT commands). Transcript files arc 
generated by default, but you can turn the transcript switch ON or OFF (sec SCRIPT command). If the 
transcript switch is turned OFF in the default command file the generation of a transcript file is suppressed. 



The sym file contains the names of the variables and routines declared in the program. The qmap Tile contains a mapping between 

qcode offsets in the scg file and the corresponding source statements. 

2 

DEBUG expects the name or the number of the target process as parameter, which can be found with the shell command SYS. 
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A transcript file has the name "M.kscr.i", where M is the cxtcnsionlcss name of the file containing the main 
program, and where i = A,...,Z. If the name space of the transcript files is exhausted, you are prompted for 
a file name. 

At the beginning Kraut prints out a stack trace of the last 4 routine calls. If the symbol table information 
files exist, calls arc written out in terms of the source program. If no symbolic information is available, the 
low level debugger Mack writes out the routine call in terms of the target code. For example 

| Uncaught exception: Division by zero 

| [tXCCPT"KAISEP] Q321(19,4,2306,2306, ...) 

| DODIV (23 test.pas;l) j := a div parm; 

| EXECUTE (17 sys>user>bob>bug .pas; 1 ) Dodiv(a.parm) ; 

| ? MAIN (34 test. pas ;1) parm := 0; Execute(parm) ; 

shows the trace of a program that did not catch the exception Division by Ze ro. The source line for 
the routine on top of the stack could not be found, because the defining module was compiled with the 
noscrounge switch. The next three lines are given in terms of the source text. The last source line is 
marked with a '?' indicating Uiat the symbolic information was not generated at the same time as the seg 
file. If the top routine is a predefined exception, the current routine is automatically set to the routine below 
die top routine, otherwise the current routine is set to the top routine. 

Kraut looks for 2 files 3 whose names arc derived from the cxtcnsionlcss file name M containing the main 
program declaration. The file M. switches defines certain user definable constants and switches such as 
the prompt sign and whether a transcript file of the debugging dialogue is to be generated. The M. kmd file 
must be a Kraut command file and its commands arc executed before any other command can be typed in 
by the user. If M . swi tches docs not exist the debugger assumes the following defaults: The prompt sign 
is "|" and die transcript switch is ON. If M. kmd docs not exist, control is immediately handed over to the 
user. 



File lookup is always done with Accent's file search list 
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Chapter Two 
Naming 

Since Kraut is a symbolic debugger it should be able to access any object mentioned in the source 
program. However, in many cases the current symbol table format docs not provide enough information to 
access the full name space or to enforce Pascal's type rules. This section describes several extensions made 
to the Pascal syntax to allow symbolic debugging despite these constraints. 

2.1 Constants 

A constant can be prefixed by a '#', a base indicator and a type indicator. The base is indicated by B, D, H 
or O (binary, decimal, hexadecimal or octal) and the type by L or I (long or integer). If the base or type 
indicator is omitted, the defaults D (decimal) or 1 (16 bit constant) arc assumed. A normal Pascal constant in 
the range -32768 to + 32767 is of type integer, otherwise of type long. 

Examples: 

0OL4743337 32 bit octal long 

#HLABF9DC93 32 bit hexadecimal long 

#b0101110101111100 16 bit binary 

#3434 16 bit decimal integer 

3434 16 bit decimal integer 

986966 32 bit decimal long 

2.2 Types 

The debugger tries to do some type checking and issues a warning if it finds a violation of Pascal's type 
rules. However, only simple types arc checked correctly. Arrays arc of the same type if they have the same 
subtype. Records arc considered equivalent if they have the same length. All pointers arc of the same type. 

The type of any variable or Pascal expression can be explicitly specified by one of the following type 
qualifiers: 
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:array["nl 


Array 


rboolean 


Byte 


:char 


Char 


: integer 


Integer 


j_[ong 


Long 


rpointer 


Pointer 


: recordTnl 


Record 


: real 


Real 


: string 


String 


:set[n] 


Set 



Kach type qualifier is uniquely specified by the underlined characters. The optional expression [n] 
specifies the wordsize of the structure. If [n] is not given, the default [1] is assumed. 



Examples: 
Var 



a: array[0..10] of integer; 

rec: record 

a,b,c : integer; 
d : pointer; 
end; 

i.gi : integer; 



a[j]:hng denotes a 32 bit variable. 

(rec.3t:long + 5*gi:integer):s is interpreted as string. 

gi:int:= #bllOlOlllll assigns the bit pattern 0000001101011111 to gi. 

i:set[l]= prints out the value of / as 16 bits 4 . 

2.3 Scope Rules 

KRAUT allows you to circumvent the scope rules of Pcrq Pascal. For example, variables from the private 
section of a module can be accessed, even if they arc not visible. The Pascal notation for an identifier has 
been extended: To denote the variable Foo in routine P you can write P'Foo.AndM* 'P'Foo denotes the 
variable Foo in routine P in module M. More generally, M' ' P x ' . . . ' P^' P n , i denotes variable i in 



Note that the least significant bit is printed out first 
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routine P n nested in P n ., nested in P,, which is declared in module M 5 . One can also access local variables 

of routines currently allocated, but not visible. Local variables of activated routines that arc outside the 
current static scope can be accessed by specifying the call chain in front of the variable name. A call chain 
consists of names of routines separated by a back slash ("\"). For example M' ' P\M1 ' ' foo\Ml ' ' foo * i 
denotes the variable i in the second invocation of routine foo in module Ml called from routine P in 
module M. 

Such a denotation may specify an object that is currently not in existence. If it is not part of a predicate (sec 
section .11), the debugger prints an error message and returns to the user level. For predicates, a 
three-valued logic is assumed and predicates that cannot be evaluated will yield the predefined value 
^-UNDEFINED. Any composite predicate containing undefined values will also yield ^UNDEFINED. 

Identifier search in Kraut follows the following algorithm: 

1. If the name docs not contain a module or routine qualifier, then it is parsed according to Pcrq 
Pascal's scope rules: First the name is looked up in the runtime stack starting at the current 
routine. If this is not successful, then the name is looked up in the current module. The current 
routine and module can be set by the CURRKNT command. 

2. If the name is of the form P ' i, Kraut searches the runtime stack for each module mentioned in 
Kraut's search list for a routine with name P. If such a routine is found, Kraut looks for the 
local variable i. The symbol tables of the modules arc searched in the order defined by Kraut's 
module search list (sec section 4.1). 

3. If the name is of the form M ' ' i, Kraut looks for variable i in module M. Note that Kraut does 
not distinguish, whether i is in the private or in the exported section. 



A nole concerning the double quote: It is not possible to use only one quote because of the possibility of name conflicts. For 
example, in ihc following program 

program foo; 
var i : integer; 

procedure foo; 
var i : integer; 

the name foo ' i could either mean the global i in module foo, or the local variable i in routine foo. 
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Chapter Three 
Path Rules 



Originally path expressions were developed for the synchronization of concurrent processes. In Kraut they 
arc used as pattern recognizers to monitor the behaviour of a target process. Path expressions are embedded 
in the more general notion of a path rule. In this section we show how path rules arc defined and give some 
examples for their use in debugging. A path rule consists of two parts: an event recognition part and an 
action part. The event recognition part consists of a generalized path expression which is discussed in section 
3.1. The purpose of the action part is to describe what the debugger has to do in the case of a match or 
mismatch of the actual computation with the computation described by the recognition part. The action 
part is described in section 3.2. 



3.1 Generated Path Expressions 

Generalized path expressions are basic path expressions extended by counters and predicates. 

A basic path expression is a regular expression of operands connected with die operators repetition (*), 
sequencing (;) and exclusive selection (|). The operands are called path functions in the following. Any 
routine defined in the source program is a predefined path function. Other path functions can be defined 
during the debugging session with the I) KM INK command described in section 4. 

If a path function R is used in a path expression it matches cither the activation or termination of the 
execution of R in the target process. Path functions can be postfixed with an event qualifier to specify cither 
the activiation or termination of a routine: If R is a path function, then R ! A denotes the activation of R and 
R!T denotes the termination of R. Thus R can be seen as a shorthand notation for the generalized path 
expression (R!A | R!T). 

A counter can be defined explicitly with the Counter command described in section 4. Furthermore, there 
are two predefined counters for each path function mentioned in a path expression: The +-ACT counter 
describes how many times the padi function has been activated and the <-TERM counter describes how 
many times it has been completed . 

A predicate is a relational expression consisting of implicit or explicit counters and names from the name 



If these counter names conflict with names of objects in the target process, they have to be prefixed with the escape character '«-'. 
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space of the program. Predicates have to be enclosed in curly brackets and can be associated with any path 
function . There is a predefined predicate ALWAYS which is equivalent to TRUE =T RUE. 

An example of a generalized path expression is 

InitStack; 

(Push{(*-TERM(Push) - <-TERM(Pop)) < N)}| 

(Pop | Top){(<-TERM(Push) - <-TERM(Pop) > 0};)* 

which suites the operational constraints on a bounded stack of length N: i-'irst the routine InitStack has 
to be called. One of the following can then happen: Hither Push can be called as long as the size of the 
stack is smaller than N, or Top or Pop can be called if the size of the stack is larger than 0. 

Generalized path expressions can be used in two different ways: If a generalized path expression is prefixed 
by the keyword Find, the specified execution sequence is matched against the observed execution 
sequence and the path action specifies what to do in the case of a match and a mismatch. F i nd expressions 
are useful in searching for the pattern of a particular execution sequence. For example, 

FindPath BeginLoop 

WhileLoop{>ACT(Push)= N and <-ACT(Pop) = 1} 

looks for the activation of the while loop when die routine Push has been called N times and Pop once. 

The other use of generalized path expressions is to enforced particular execution sequence. If a generalized 
path expression is prefixed by the keyword Check, the specified execution sequence is matched against the 
observed execution sequence. The path action contains commands about what to do in the case of a 
violation or nonviolation. For example, 

CheckPath Loop 

(WhileLoop{*-ACT(Whi1eloop) < 6} | Pop)* 

says that the while loop should not be executed more than 6 times before a call to Pop occurs. 

Any identifier that is used in a predicate of a generalized path expression is called a path variable. 
Predefined path variables are identifiers explicitly declared in the source program and accessible via the 
symbol table. 



7 

If a path function P is mentioned without counters or predicates the defaults <- ACf'(P) >= and *-TL-RM(P) >= arc assumed. 
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3.2 Path Actions 

A path action is declared by the keyword Action followed by the identifier of the path expression with 
which the path action is to be associated. The keywords Match and NoMatch arc followed by the actions 
to be taken in case of a match and mismatch, respectively. Any sequence of debugger commands not 
containing an assignment or routine call is a valid action. Assignments and routine calls have to be preceded 
by a HALT command. If an action contains more than one command, the commands have to be separated 
by '~\ Hither the Match or the Mismatch part or both can be omitted, in which case no action will be 
associated with the missing part. 

For example 

Action Loop 

Match => Writeln("I = ", I) >> LoopWindow 
NoMatch => HALT 

associates the debugger commands MALT and Write"! n( "I = ",I » LoopWindow) with the path 
expression Loop. Thus whenever the evaluation of Loop yields a violation of the specified ordering the 
computation is suspended and control is turned over to tne ocuuggcr, otnenvisc tnc vaiuc oi I is written 
into the window LoopWi ndow. 

The association of a path action with a generalized path expression is dynamic. Thus you can remove a path 
action from a path rule and replace it by another path action. This can be done any time the target process 
is suspended: If the process is still running, you can suspend it with the characters ?DEL k or tDEL d (see 
page 19). 



3.3 Manipulating Path Rules 

Path rules arc automatically enabled when they are defined. They can be disabled and enabled again by the 
DISABLE and ENABLE commands described in section 4.6. Note that if a Match or a Mi smatch occurs, 
the path rule is not automatically disabled. Disabling a path rule and successive enabling has to be done 
explicitly. Every time the Match part of a path rule is executed the path rule is set to its initial state, that is, 
is starting over again to look for the pattern specified in the generalized path expression. 



Note thai the generalized path expression LOOP is only evaluated when one of its path functions is executed 
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Chapter Four 
Command Language 

Any command can be abbreviated as long as the abbreviation is unique. For convenience, an attempt has 
been made to allow two letter abbreviations for nearly all commands. Because of this reason some of the 
command names might look a little bit strange. Commands and variable names are not case sensitive. For 
example, \V and Y mean the same command or identifier. If more than one command is entered per line, 
the commands have to be separated by the character "~". A command or command sequence can be 
extended over several lines. Hach of the lines of such a command has to be terminated with a 'Y character. 
For example, 

cal IstacA 
k l~writ\ 
eln('I = ' ,I)~\ 

go 



is parsed as: 



callstack l~writeln('I = ',I)~go 



At any time the debugger maintains a current line number and a current source file which can be denoted 
by the dot character ("."). 



4.1 Search List Commands 

Kraut maintains a search list of open modules which determines the order in which symbol tables arc 
searched for identifiers. The search order is the reverse of the order in which the modules arc entered: The 
module opened latest will be searched first. By modifying the search list appropriately you can speed up the 
debugger significantly. The module search list is initially empty. Any time the target process is suspended, 
the modules of routines on die runtime stack not yet in the module search list arc appended to the tail of 
die module search list. Modules arc never implicitly removed from the list. 

Kraut looks up the source, qmap and sym files of a module using the current file search list. The 
SETSEARCH command can be used to add directories to the file search list. This makes it possible to 
access remote files from inside the debugger. If the file search list did not contain the directory in which the 
source or symbolic files arc located, when the module was OPENcd, Kraut will try to open the module 
without this information. If you want to add theses files later, CLOSE the module, call SKTSEARCH with 
the appropriate (remote) directory and then call OPEN again. 
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ChDirl) 



Open !VI 



Close M 



Set the current directory to D. If no argument is specified, show the current directory. 



Insert module M at the head of Kraut's module search list. If the module is already in the 
search list, it will be moved to the head of the list. The variable Current File is changed to 
the file name of the module opened. If M is a list of modules M, M, ...M , then open each 
of the modules as described above. If M = * , then open all the modules of the target 
process, except for the modules of the Pascal runtime system. The latter ones can be 
opened with the System command. 



Delete module M from Kraut's search list. If M is a list of modules M, M 2 ...M , then 
delete each of the modules. If M = * , then close all the modules of the target process. 



SetSearch Fj ',..., F n 

If no arguments are given, then show Accent's file search list. Otherwise modify the file 
search list as follows: If Fj is a directory name, push it on the search list, if b\ is a "-" then 
pop the top entry from the search list. 



Show Modules M 



System 



If M is not given, show all open modules from Kraut's module search list. Otherwise give 
some information about module M. This includes date of compilation, names of scg, qmap 
and sym files, name of imports, etc. 



Initially the Pascal runtime system modules arc not in the search list, even if they arc 
explicitly imported by the user program. The Pascal runtime system consist of the module 
Pascallnit and all its imports. System opens tiicsc modules and adds them to the search 
list. 



4.2 Trace Commands 

Traces are implemented internally as path rules. For each routine R to be traced, two padi rules arc created. 
The first one has the name *-AR and monitors die Activation of R. The second one has the name <-TR and 
monitors the Termination of R. The MATCH part in the path action is preset to print whether the routine is 
entered or exited. Traces can be edited with the Edit Path Rule command (sec page 15). 



Kraut - User Manual 



12 



Truce [Before |Afterl R [UserActions] 

R can be cither a module or a routine. If R is a module tracing path rules are created for 
each routine defined in the module. If it is a routine and neither Before nor After is 
specified, both path rules <-AR and «-TR arc created. If Before is given, only the path rule 
<-AR to trace the entry of R is created. If After is given, only the path rule <-TR to trace the 
exit of R is created. If "UserActions" is specified, then "UserActions" arc executed 
whenever one of the trace path rules fires. 

DTrace [Before | A fterJR 

If R is a routine delete the tracing path rules for R. If R is a module delete the traces for all 
routines of R. If Before (After) is given, delete the only the padi rule for the entry 
(exit) of R. 



4.3 Breakpoint Commands 

Setting of breakpoints can be done either by specifying a source line or by a routine name. In the following, 
the symbol R denotes a routine. R can be of the form M ' ' P or P. The symbol '#' denotes a source line in a 
source file in a certain directory. If the file name is omitted, the current file is assumed. The line number 
must correspond to a source line containing the beginning of a Pcrq Pascal statement, otherwise Kraut 
writes an error message. Breakpoints arc implemented internally as path rules. The name of the path rule is 
of the form <-B# , where # is in the range 1..150. The MATCH part in the path action is preset to the 
command sequence Hsilt~Kxccption~Callstack !. Breakpoints can be edited with the ED1TPATHRULE 
command (see page 15). 

NOTE: The Halt command is part of the definition of a break point and cannot be removed from the 
MATCH part. 

Break (after) R , Break # 

Set Breakpoint at (after) routine R or at line #. For example Break 4 main, pas 
means: Set a break point at source line 4 in file main.pas. 



9 

Note that the character "+-" is actually the character "_" on your keyboard 
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DBreak * 



Delete all Breakpoints. 



DBreak (after) R, DBreak # 

Delete Breakpoint at (after) routine R or line #. 



Show Breaks 



Show current breakpoint list. This command is the same as Show Pathrules if no other 
path rules but breakpoints arc active. 



4.4 Editor Commands 



The following commands allow you to inspect source file and search for string patterns. If a new file name 
is specified, the current file will be set to the new name. 



Type i j F 



Around i F 



Scroll i F 



Search 'SI F 



Show source lines i to j in file F. The current source line is set to the last line displayed. F 
must be visible with Accent's file search list. There are several abbreviations of the type 
command: The keyword Type can be omitted. If the file name is also omitted, then the 
current file is assumed. Furthermore, the commands i F or'i will display line i in file F or 
in the current file, respectively. 



Show 20 source lines around line i in file F. Line i is indicated by '***'. If F is omitted, die 
current file is assumed. If i and F arc omitted the current source line is assumed. 



Type 20 source lines starting at the current source line. The Next command can be used 
after the first scroll. 



Search backward in file F for string S. If S is omitted take the string from the last search 

command. If S contains a " ,M , then two have to be specified. Note that the search is not 

case sensitive. If F is omitted, the current file is assumed. ITS' is found, the current source 
line is set to the line containing 'S\ 
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Search 'S'! F 



Grep 'S' F 



Search forward in file F for string S. The T can be omitted if S is given. If S is omitted 

take the string from the last search command. If S contains a '"", then two ' have to be 

specified. Note that die search is not case sensitive. If F is omitted, the current file is 
assumed. ITS' is found, the current source line is set to the line containing 'S\ 



Look for all occurences of string S in file F. The search is case insensitive. If F is omitted 
than do string search stinting at the current source line in the current source file. ITS' is 
replaced by !, then look with the last string pattern specified. Currently neither S nor Fcan 
contain wildcards. 



4.5 Definition Commands 

Kraut allows the definition of new path functions, counters and paUi variables which can be used in 
generalized path expressions in the same way as that for predefined names. 



Counter C : = 1 



DCountcr C 



Declare a counter variable C and assign it the value I. If die assignment is omitted, the 
counter is initialized to 0. Counters are regarded as global variables defined in a static 
scope surrounding the main program. If there is a variable with the same name defined in 
the program, Kraut prefixes the counter variable with the escape character '*-' and asks 
vou for confirmation. 



Delete the counter variable C. 



Define Function P B E 

Associate the path function P with a group of statements indicated by the source lines B 
and E in file F. B and K must belong to the same source file and the source line denoted by 
B must be smaller than the source line denoted by E. 

4.6 Path Rule Commands 



The debugger maintains a list of path rules which can be defined and manipulated. In the following, R 
denotes the name of a path rule and can be any identifier. 
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Action R A 



Hind action A to path rule R. The arguments R and A can be omitted, in which case you 
arc prompted for them. R must have been defined before by a F i ndPath or CheckPa th 
command. A is of the form: 

MATCH Cmdl NOMATCH Cmd2 

Cmdl and Cmd2 can be any Kraut command or command sequence. The Match part 
has to be defined before the NOMATCH part. Command sequences must be enclosed in 
parentheses. If the execution sequence matches the sequence specified by the generalized 
path expression, then Cmdl is executed. If there is no such match, then Cmdl is executed. 
For example 

Action Rl MATCH (calls-br f i rstcal ]~disab !e Rl-enable R2) 

executes the Calls command, sets a breakpoint at routine f i rstcal 1, disables itself and 
enables path rule R2. 



Check Path R G 



Disable R 



Kditpathrulc P 



Qualify R as a Check rule and add it to the active path rule list. G is a generalized path 
expression (see section 3.1). If the arguments R and G arc omitted, you are prompted for 
them and for the associated path action. 



Disable the currently active path rule R. This command takes the padi rule R from the 
active path rule list and appends it to the list of inactive path rules. 



This command allows to change the components Generalized Path Expression, Match and 
NoMatch of path rule P. Furthermore the user is prompted for the setting of two switches: 
The ENABLED switch enables P if set to true, otherwise disables it. If the VERBOSE 
switch is set to true, the interpretation of the path actions is done verbose, otherwise quiet. 
Note that editing of path rules created by the BREAK command is restricted in the following 
way: It is not possible to change the whole Generalized Path Expression associated with the 
breakpoint, but only its predicate. Predicates can be entered when the CONDITION prompt 
is given. 
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Enable R 



The following example sets a breakpoint at line 86 and changes the default action to do the 
following commands: Print out the callstack to depth 4. print the locals of the current 
routine, write the value of i and continue. The action will only occur if the target process 
executes line 86 and i has the value 1000. 

|BREAK 86 test3.pas 

|Set Breakpoint «-Bl at line 86 in TEST. PAS: wri te( ' F irst; ' ) ; 

I 

JEDIT «-Bl 

| CONUITIOM [] : i = 1000 

I MATCH [J : Callstack 4~local s~writel n( ' i = *, i)~go 

| NOMATCU [] : 

| ENABLE [] : TRUE 

| VERBOSE [] : TRUE 



Enable the currently inactive path rule R. This command takes die path rule R from the 
inactive path rule list and appends it to the list of active path rules. 

FindPathRG 

Qualify R as a Check rule and add it to the active path rule list. G is a generalized path 
exprcssion(scc section 3.1). If the arguments R and G arc omitted, you are prompted for 
them and for the associated path action. 

Show PathRiiles (enabled | disabled ) 

Show the active or inactive patii rule list. If no argument is specified show the entire path 
rule list. (This command is equivalent to Slum PathRulcs). 

Show Path Rules F 

Show the components of path rule F. 

RcmovcPath P 

Delete path rule P from the path rule list. If P is a list of path rules P 1 P 2 ... P n then remove 
each of these path rules from the list. 

Remove Action R 

Delete the action bound to path rule R. 
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4.7 Variable Inspection Commands 



In the following V and Id denote identifiers as defined in section 2, page 4, counters as defined in section 
4.5, page 14 or history variables. Id can also be an arbitrary Pascal expression with the restrictions 
in section 7, page 37. 



Globals M 



Display all globals of module M. 
module. 



If M is not specified, display the locals of the current 



Locals R 



Parameters R 



Radix N 



V = 



Display all locals of routine R. If R is not specified, display the locals of the current routine. 



Show die current values of the parameters of R. If R is not specified, then show the 
parameters of the current routine. 



Set the current radix to N where N is a decimal number from the set { 2,8,10,16}. Initially 
the current radix is 10. 



Get the value of V following the scope rules as described in section 2.3. If the name of the 
variable is not also a Kraut command, then the equal sign ( = ) can be omitted. To avoid 
confusion arising from names used in more than one module, values arc always written out 
in the form "value [Module/'. Module is the name of die module containing V or it is die 
string Internal Counter if V has been defined as a counter variable. If the value was 
retrieved from an inconsistent symbol table, the module name is marked with a T sign. 



Id 



Assign the value of Id to V following the scope rules described in section 2.3. V cannot be 
a history variable. The debugger tries to do some kind of type checking as described in 
section 2 and issues a warning if there is a violation. 

Write(pl,p2 pn), Writeln(pl,p2,...,pn) 

Write and Writcln are similar to Pascal's write and writcln. The only difference is that die 

output is always written in the current window. ? { ,? 2 P n can be any Pascal expressions 

with the restrictions and extensions described in section 2, page 4. For example, if foo = 
'df and has = 1, then Writclii('KOO = \ foo, 'BAS = \ bas) results in the output: 

FOO = 'dfBAS = 1 
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4.8 Next Command 



<CR> 



This command is interpreted in the context of the last command. The next command is 
implemented for the following commands: 



$ 

Around 
Calls 



DownStack 
Forward Search 

Scroll 
SingleStep 

Type 

UpStack 



Mace command: Display the next location in the current mode and 
current radix. 

Show the next 20 source lines in the current file. 

Display one more call. The current source line and file are updated 
to the line displayed, so typing Around after this command 
displays the context around the source line. Note: The current 
routine is not changed. 

Move down one activation record in the dynamic call chain. 

Continue the search with the previous argument storting at the 
current source line. 

Show the next 20 source lines in the current file. 

Hxccutc one more source line. 

Show the next 20 source lines in the current file. 

Move up one activation record in the dynamic call chain. 



4.9 Runtime Stack Commands 



BottomStack 



Calls N 



Set the current routine to the routine described by the activation record at the bottom of 
the runtime stack. 



Display the dynamic calling sequence of the target process. N specifics the number of calls 
to be printed. If N is omitted, then the whole sequence will be printed. 
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DownStack N 

Move down one activation record towards the bottom of the runtime stack and update the 
current routine. I f N is omitted, N = 1 is assumed. . 



TopSlack 



UpStack N 



Set the current routine to the routine described by the activation record at the top of the 
runtime stack. 



Move up N activation records towards the top of the runtime stack and update the current 
routine. If N is omitted, N = 1 is assumed. 



4.10 Target Process Control Commands 



These commands allow to modify or observe the execution of the target process. 

Process Control Characters 

The process control characters tDKL c, tDKL d, tDKL k and tDKL t are intercepted by 
Kraut. Their interpretation depends on the context of the last command: 

KXKCUTRGO 

tDKL t: Show the state of the target process. (Not yet implemented) 

tDKL c, tDKL d, tDKL k: Suspend the target process and return to command level. 

tDclr:NOOP 

All other commands 

tDKL t: Show the state of the target process. (Not yet implemented) 

tDKL r,tDKL d: Abort the current command. 

tDKLc:NOOP 
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Kxccule R(p,,p 2 P n ) 

Kxecutc routine R with parameters p,,p 2 p n . R can be the main program, any global 

routine or a nested routine statically visible from the current point of execution. If R is the 
main program, you are prompted whether the run time stack shall be cleared or not. If R 
has been defined with parameters, they have to be passed, but the debugger does no type 
checking at all. If the closing parenthesis is omitted, the debugger writes out the type 
information for each parameter and asks for confirmation. The syntax for parameters is 
similar to Rascal's syntax except for the following two cases: 1. Var parameters must be 
prefixed with a V. 2. Normal Rascal constants arc treated as integer decimals if they arc in 
the range -32768. .32767, otherwise as long decimals. Other constants have to be prefixed 
by a '#', a base indicator and a type indicator as described in section 2.1. For example: 

Execute Foo(tBar, 34, #H5FA4, #BL0111, Count) 

calls procedure Foo with reference parameter Bar, decimal integer 34, hexadecimal integer 
5FA4, binary long 0111 and value parameter Count, The variables Bar and Count are 
visible from the current point of execution. 

If R is a function, more restrictions have to be observed, most of them due to the 
insufficient symbol table information provided by the compiler: Functions names must 
always be indicated by parenUicscs followed by a Type Qualifier. Parentheses are needed 
even if the function docs not have any parameters, otherwise the result of the function is 
denoted. Functions can be used in arbitrary expressions, but cannot be passed as 
parameters. 



WARNING: // is easy to do something wrong when calling a function from inside the 
debugger. The following examples show how to use function calls and how not: 

Type REC = record i : integer; 1 : long end; 

Var b : boolean; r : REC; 

Function foo(i : integer): boolean; 

Function fool: boolean; 

Function bla(s : string[80]): REC; 



Legal calls : 

b := foo{ i) : boolean 

b := fool() 

fool() -- displays result of function call on screen. 

r := bla{ 'sdfsfd' :st.ring[80]) : record[3] -- assigns the value of bla tor 

bla('sdfsfd' :string[80]): record[3] - - types (he value of bla on on the display. 



Illegal calls : 
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b := foo(i) -- missing type qualifier 

Problematic calls: 



b := fool -- Missing parentheses: 

The debugger takes the current return value 

of fool instead of calling fool . 
r : - b 1 a ( ' s d f s f d ' ) : r e c o r d [ 3 | - - takes default value of string leng th . 



Resume the execution of the suspended target process. 
Suspend the execution of the target process. 



Delete the link to the current target process and start the execution of target process T. 
'This command is useful for debugging a new target process, for example if the current 
program has been recompiled and relinked, without leaving the debugger. NOTK: If you 

jUai vVcuiL iw iv-auiii ulc <_u»iLut ixu t^ci. jji wv^ab, Ubv tiiv. i;av*.uiv wutimiaiiu wilii luv ikiliiv. kji 

the main program as parameter. 

TerminateTarget Y KSjNO 

Terminate or do not terminate the target process on QUIT. Initially TerminateTarget is set 
toYKS. 

Unwind 

Remove all activation records from the runtimestack up to and including the last routine 
that was called with the HXKCUTK command. If there is no such routine the stack is not 
changed. 



4.11 Miscellaneous Commands 

Execute command file F. If F is not specified, die command file M.kmd is executed, 
where M is the cxtcnsionlcss file name of the main program . Command files can be 
nested to an arbitrary depth. If F does not contain an extension and there is no file with 
the name F, then the extension .kmd is appended. 



M.kmd is the default command file. If it can be found with the initial file search list, it is automatically executed at the beginning 
of the debugging session. 
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$M 



& 



Address 11) 



Compute K 



Current M 



Kxccute the Mace command M without leaving the Kraut command interpreter. Mack 
commands are described in section 5. 



Start of a comment. Any string following the two dashes up to the end of the line is 
regarded as comment. 



If the result of the last debugging command was a numeric value, it can be denoted by the 
symbol &. & can be used in any Pascal expression. The symbol &t interprets the value of 
the last command as a pointer. Thus it especially useful for pointer chains. 



Show the target address of ID. ID denotes an identifier as defined in section 2.3. If ID is a 
routine, then show the addresses of its entry and exit points. If ID is omitted, the identifier 
from the last debugger command is taken. The address command allows you to inspect 
ID's more closely with Mace if Kraut docs not provide any help (for example for record 
fields).} 



Compute expression H. The Compute command evaluates (nearly) any pascal expression. 
The keyword COMPUTKcan be omitted if the expression starts with a constant . If the 
type of a variable is not known or has to be recastcd, use type qualifiers. For example, if 1 
is an integer and W a function of type integer and the result is of type real, the following 
command computes the real value 400022 + 5*7-i + w(i): 

COMPUTE (400022 + 5*7- i+w( i ): integer) : real 



If M is a module, set the current module to M (This is equivalent to Open M). Otherwise, if 
M is an active routine, set the current routine to M. If M is not active, do not change the 
current routine. If no argument is specified the current module and routine arc displayed. 



11 



Note thai any single digit will be interpreted as a source line number of the TYPE command. 
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Kxccption 



Help 



Indent N 



Maintainer M 



Mace 



News 



Quit 



Show the current exception. 



Creates a help window and allows the user to interactively peruse the appendix of this 
manual. 



Concatenate N blanks with the prompt sign. NOTE: In the case of a command error or 
when tDEL c, tDEL k or tDEL d is typed, INDENT is automatically executed. 



Print out the name of the maintainor of module M. This command prints out the string 
following the key word Maintainer in the comment switch in module M. For example, if 
module TEST contains {SComment Maintainer bobQcmux x3828} in the source 
file, then "bob@cmux x3828" is the maintainer of TKST. If M is omitted in the 
command, then the maintainors of all maintained modules arc printed out. 



Enter the command interpreter of mach, the low level Accent debugger. Mack commands 
arc described in section 5. To return back to the Kraut command interpreter type the 
Mach quit command. 



Print out news about undocumented features, new bugs and fixes of old bugs. 



There arc four possible courses of action when choosing to quit the debugger. They arc as 
follows: 

Quit Exits the debugger. 

Continue Resumes the debugging interaction. 

Report Refer to the Report Command below. 

SaveScriptAndQuit Automatically saves a transcript of the current dialogue if the 
U'anscript switch was On at least once during die debugging 
session;then exits from the debugger. 
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Report M 



Script on|off 



Silence on|off 



Shell 



Create the transcript of the debugging session to be deposited in the outgoing mail for the 
mailing address M when the QUIT command is typed. If M is omitted, the account 
Spice@spice is assumed as the receiver. When quitting you are asked to confirm the 
mailing address, the l ; ROM field (which is taken from the first line of the file 
<boot>sysnamc) and whether you want to provide an additional message. The message can 
be in a file or it can be typed in the window. A typed message has to be terminated with a 
single dot on a line. The Report command can be typed at any time of the debugging 
session. Note that Kraut is not doing the actual mailing. It only puts the transcript in a 
file <hoot>perqout.R*, from where it has to be picked up by the mail system. 



KXAMPLK (user input is underlined): 

I Report bob, dzq 

JMail request to bob, dzg registered 

| ... 

I Quit 

JAction (Quit, Continue, Report, SaveScriptAndQu i I ) [REPORT] ? < CR> 

JMailing transcript... 

I TO : [bob, dzg] bob@cnui-cs-sp ice , hibbardQcmua , ots 

[FROM [bob@cmu-cs-spice]: <CR> 

|Subject [Bug in test]: <CR> 

JDo you want to add an initial message? (Yes, No) [YES] Yes 

JEnter file name or hit <REIURN>: <CR> 

JType message (terminate with a "." alone on a line): 

Hi, I found the following bug: 

(Preparing mail . . . 

I ...Mail deposited for bob@cmu-cs-spice, hibbardQcmua, ets 



Turn the transcript on or off. If Script off is contained in the default command file, 
no transcript file will be generated at all. 



If silence is on, then the commands executed in a command file will not be echoed on the 
curcnt window. If silence is off, they arc echoed. The default value is off. 



Spawn another shell, inheriting the environment in which Kraut is currently running. 
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Sliow P 



Version 



Depending on the parameter P the Following is displayed: 



P= Breaks 
P= Counters 
P= Models 
P= Modules M 



P=Pathfunctions M 



P=PathrulcsPl 



P= Routines M 



Show the current break point list. 

Show the currently defined counter variables. 

Show the current models. 

If M is omitted, then type Kraut's module list. Otherwise give 
some information about module M. Tins includes date of 
compilation, names of scg, qmap and sym files, name of imports, 
etc. 

Show the user defined path functions for module M. If M is 
omitted show the user defined path functions of all modules. 

If Pl='activc' then display the list of enabled pathrulcs: if 
PI = 'inactive', dien display the list of disabled path rules, otherwise 
display all path rules currently defined. 

Show the routines and user defined path functions for module M. 
M must be in the module search list, if M is omitted show the 
routines and user defined path functions of all modules. 



P- RunFile (R M) If R and M arc omitted, print die core image of the current target 
process into die file M.map, where M is the extcnsionlcss filename 
of die main program. If R and M arc given, then print die contents 
of run file R into file M. Note that in this case some fields in the file 
and segment entry descriptors arc set to and do not describe 
locations in the address space! 

P= Search List Display Accent's file search list. 

P= Window Display the currently defined windows. 



Type the version number of the debugger. 



4.12 Window Commands 

The following commands allow die user to define typescript windows, change from one window to another 
and display information in any defined window. There arc two predefined windows, which arc treated 
differently from user defined windows: The DEBUG window is the window allocated by Accent when the 
debugger is started up. The DEBUG window is treated in such a way that it allows the debugger to run even 
if the window manager is not running. The Barg raphWi ndow is a graphic window in which variables can 
be bound to bargraphs (see section 4.13). 
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There is always a current window, which is originally set to DEBUG. There may be a maximum of ten 
windows, each of which may be manipulated by all of the normal Saitiiirh commands (top, bottom, move, 
grow, etc.). 

Window W LX TY W H 

Creates window W with upper-left corner LX, TY and VV characters per line and II lines. 
If these coordinates are omitted, default coordinates are used. 



Window W 



I) Window W 



DWindow * 



C»W 



Creates window W. Typing Window W a second time brings window W to the top and 
makes it the listener. 'This command is used to move the listener from one window to 
another. 



Deletes the window with the name W. 



Deletes all windows but the current one. 



Redirect the output of the Kraut command or command sequence C into window W but 
do not leave the current window. If W has not yet been defined, a window with default 
coordinates will be created. 



4.13 iVSodel Commands 

Model commands allow you to display variables with a format different from the built-in display format. A 
model is a display template defined by a Model command. Bargraphs arc predefined models. Models are 
instantiated by the Bind command and it is possible to bind several variables to the same model. 

Model Bargraph I? MAX S 

Create or rescale a bargraph with the name B, where B can be any identifier. If B has not 
yet been defined, a template for B is created. The maximal value of the template is given 
by the integer MAX. S describes the scale and can be cither LINEAR {linear scale) or LOG 
(logarithmic scale). MAX and S can be omitted in which case the defaults MAX = 32767 
and S = LINEAR arc assumed. If the bargraph B already exists, the template and all its 
instantiations are rcscalcd according to the new values MAX and S. Note that the keyword 
Model can be omitted in the command. 
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Model Routine M R 

Create a model with the name M, where M can be any identifier, and bind the routine R to 
it. The keyword Model can be omitted in the command. R can be any procedure defined 
in the user program and may have parameters. All except for one of R's parameters have to 
be bound at the definition of the model. It is possible to mark one of the parameter's slots 
with a "$" character and this parameter will be bound by the Bind command. Kor 



Bind ID M 



example. 



Model Routine M Foo(tgi, #123, $) 



binds die routine Foo with g i, #1 23 and $ to the model M, and $ will be provided by the 
Bind command. 



Bind the variable ID to a model with die name M. Currently two classes of bindings arc 
possible: 

1. If M is a bargraph, then ID can be a counter, a history variable (ACT or TKRM) 
or a variable of type integer. The debugger allocates a slot in the window 
BargraphWindow and displays ID according to the attributes of M" . For 
example 

Bind <-ACT(Foo) M 

binds the history variable <-ACT(Foo) to the bargraph M. After a variable is 
bound to a bargraph, any display command will display its value according to the 
scale and maximum value of die bargraph. If 11) is a counter or a history variable, 
the bargraph is updated on any assignment. However, if ID is a program variable, 
the bargraph is not updated until the next display command is issued. 

2. If M is a routine, dicn ID can be a variable of any type. If M has been defined with 
parameter "$", then ID is substituted for "$" in M. Kor example, the commands 

Model Routine M Foo(tgi, #123, f$) 
Bind grec M 

define a model M for routine Foo and bind grec to it. Displaying grec will 
result in calling Foo( tgi ,#123 , tgrec). 



12 



If BargraphWindow does not yet exist, you arc prompted for the screen locations. 
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DModel M 

Delete the model M. 

DRind II) 

Delete ID's binding to a model and rcbind it to text format. 
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Chapter Five 

Mace 



The command syntax for Maci- is quite different from that for KraU'I*. Some Mack commands may 
contain Maci- expressions and qualifiers to change the radix and mode of the entities being displayed. The 
radix or mode qualifier is optional and if omitted the current radix or mode is assumed, respectively. The 
radix qualifier controls the radix of numbers and can have one of the following values: 



# Octal radix 

Decimal radix 



Tic mode qualifier specifies the type of objcct(s) to be displayed and can have one of the following values: 



a 


16 bit integer, 32 bit long, byte, 




character and string (max 15 characters) 


b 


Byte 


c 


Character 


i 


16 bit inteoer 


1 


32 bit long 


m 


IPC Message 


q 


Qcode 


r 


Floating point 


s 


Pascal string 



A Maci- expression is a parenthesized expression of primary values using one or more of the following 
operators: 



t 


Dereference (written after the value) 


6 


- 


Negation 


5 


~ 


Logical inversion 


4 


* 


Mul tipl ication 


3 


/ 


Division 


3 


I 


MOD 


3 


+ 


Addition 


2 


- 


Subtraction 


2 


& 


Logical And 


1 


% 


Logical Or 


1 


< 


Leftshift 


1 


> 


RightShift 


1 



The operators are ordered in decreasing precedence. Parentheses can be used to indicate different 
precedences. 
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A primary value is one of the following constructs, where <M>, <P>, <N> and <K> arc Mac!-: expressions 
denoting addresses and numbers. 



892 


Any decimal constant 




#377 


Any octal constant 

The last location referenced. 




<M> 


Base address of the code segment of module M. 




<P> 


Entry point of routine P. 




<M>.6*<E> 


Offset E in the global frame of module M. 




<M>.tf<E> 


The E'th word in the routine dictionary of module 


M. 


<M>"<P> 


Entry point of routine P in module M. 




<P>.£KE> 


Offset E in routine P. 




<P>./KE> 


The E'th word of the ACB for last call to P. 




<P>.<N>/kE> 


The E'th word of the ACB for 
the N'th call to P. 




<P>.F<E> 


The E'th local word of last call to P. 




<P>./?<E> 


The E'th word in P's routine diet entry. 





Examples for Mao: expressions arc 



Test3.Procl + #557t Procedure Prod in module TestJ 

plus contents of address octal 557. 

Procl.4A3 The third word in the ACB for the 

fourth call of procedure Prod. 

Foo.Q23 - . Qcode offset 23 in routine Foo minus 

last expression referred to. 



The following example shows the order of evaluation of Maci- expressions: 

Foo.Q5 * Test.G45 & ~3 - 5t 
is evaluated as 

(Foo.Q5 * Test.G45) & ((~3) - (5t)). 
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5.1 IMAGE Commands 



In the following <H> and <V> denote Mack expressions, <R> a radix qualifier, <M> a mode qualifier and 
<D> a decimal integer. Note that command names are case sensitive, whereas Mack expressions are not. 

?, h, h:? 

Type help information. The commands ?,h and H explain Mack expressions and die " ; ", 
"=" and " : =" commands. The command ' ? explains the " ' " commands. 

<R>; <R> <M> <D> 

Display <D> target memory locations starting at <K> in the format specified by mode <M> 
and radix <R> in units appropriate for the given type. <D> must be a decimal integer. <B> 
can be any Mack expression. For example: 

Foo.q54; .q23 



displays 23 locations starting at address Foo.q54 as qcodc instructions with decimal 
arguments. 

<E>=<RXM> 

Calculate the Mack expression <R> in mode <M> using radix <R>. For example: 

87506 + 45*7=#i 



<E>:=<V> 



displays the value of 87506 + 45*7 as an octal integer. 



Store the value <V> in the 16 bit location <E>. <H> and <V> can be arbitrary Mack 
expressions. For example: 

Test.G456 := Foo.F4 



stores the value of the 4'th local word of routine Foo into offset 456 in module Test. 



Kraut - User Manual 



<D>'a 



32 



If <l)> = l,2...,100, then show the contents of the <D>Th activation record (ACB) on the 
stack. <l)> = 1 means the ACB of the top routine and <D> = n means the n'th ACB down 
towards the bottom of the stack. If <D> is larger than 100, Mack assumes you have typed 
the address of the ACH . The ACB consists of the following information: 



ACBSL: Activation pointer (AP) of enclosing routine 

ACBLP: local pointer (LP) of this routine 

ACBDL: Activation pointer of calling routine 

ACBGL: Global pointer (GP) of calling routine 

ACBTL: Top pointer (IP) of calling routine 

ACBRS: " System Segment number (SSN) of calling routine 

ACBRA: Program counter (VPC) of calling routine 

ACBRR: Routine Number of calling routine 

ACBEP: Pointer to current exception enable record 

ACBStackSize: Size of EStack of calling routine 

ACBStackSize+i: Saved EStack values ,i= 1 ACBStackSize 



<E>*b 



<K>'d 



<D>'E<V> 



<H>'h 



Set a breakpoint at address <K>. If<H> = 0. show the list of current breakpoints. 



Delete a breakpoint at address <E>. 



Display expression stack (from the bottom towards the top). 



Jf <D>= -1, then assign <V> to the micro suite register KStkCount. which holds die current 
size of the EStack. If <D> in [0..15J then assign <V> to expression stack register <D>. (Note: 
is the bottom of the expression stack). 



Display the history for message <H>. If <E> = then display the history of all messages. 
This command assumes that the program you arc debugging imports the module 
AccCall from AccCall .pas. If this is not the case, you get the error message No 
module specif ied.AccCall must be specially compiled to enable the message 
history mechanism. (The message history mechanism is currently disabled.) 



13 

The activation pointer (AP) of a routine points to the address of its ACB. Sec ' m command, 



Kraut - User Manual 



33 



<D>'m 



14 



If <1)> = 0, show the qcodc suite of the current routine . Otherwise show the qeodc state 
for the <D>'th activated routine on the stack, counting downward towards the bottom of 
the stack. Thus, <1)>= 1 means the routine on top of the stack, etc. The qeode slate consists 
of the following information: 



SB 

CR 

GP 

VPC 

RN 

LP 

AP 

TP 



Stack base 

Base address of code segment 

Global pointer 

Program counter 

Routine number 

Local pointer 

Activation pointer (Base address of ACB) 

Top pointer 



*M 



Displays the contents of registers 5 to 16 and 11.0 of Accent's micro context block. A typical 
output for the ' M command looks as follows: 



Program counter 

Top pointer 

Activation Pointer 

Global Pointer 

Local Pointer 

Routine Number 

Code Segment 

Stack Segment 

Breakpoint register 

Exc handler code segment 

Exc handler global pointer [R 

Encode overlay 8 and entry [R 

VM status [R 



[R 


5]: 


172[#254] 


[R 


6]: 


21290[#51452J 


[R 


7]: 


21280[#51440] 


[~R 


8]: 


2562[~#5002] 


[R 


9]: 


21236[#51364] 


[R 


10] 


0[#0] 


[R 


11] 


152[#230] 


[R 


12] 


l[tfl] 


[R 


13] 


-1[#-1] 


[R 


14] 


152[#230] 


[« 


15] 


2562f#5002] 


[R 


16] 


3[#3] 



110]: 1280[#2400] 



<E>'p 



If <E> is an address within the code of any routine, then display the routine dictionary of 
that routine. The routine dictionary has the following format: 

RDPS: Size of parameters 

RDRPS: Size of result + parameters 

RDLTS: Size of locals + temporaries 

RDLL: Lexcial Level 

RDEntry: Entry address relative to segment 

RDExit: Exit address relative to segment 



14 



The current routine can be changed with the Kraut runtime stack commands UpStack, DownStack, etc. 
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<K>'P 



<D>'t 



<D>'u 



<D>'U <V> 



If <K> = 0, then show Lhc code segment base address (CB) and the global pointer (GP) of 
each module. Otherwise, show the segment header block for module <f'>. The time stamp 
attached to a file name indicates the last time the file was updated. For example, the 
command test3 ' P might display the following information: 

Program TEST3 [Compiled at: 11 Apr 83 11:33:29] 

Src file = <boot>user>bob>tesl3 . PAS [20 Aug 82 10:53:01] 

QVersion = 3 

GDB size = 184 words 

Version = ' ' 

Comment = ' ' 

QMapFile = <boot>bob> test3.QMAP [11 Apr 83 11:33:29] 

SymFile = <boot>user>bob>test3 . SYM [11 Apr 83 11:33:29] 

Imports 3 files: (Import info at block 2) 

TEST3A from test3a.PAS 

WRITER from WRITER. PAS 

STREAM from STREAM. PAS 



Terminate Mack and return to Kraut command level. Note: This command should only 
be executed on Mack, command level. 



Resume execution of the target process. 

Suspend execution of the target process. 

Show the last <D> routine calls starting at the top of the stack. 

Show the contents of micro state register <D>. 

Assign die value <V> to micro state register <D>. 
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X 



'@ 



Toggle Mack debug flag (for debugging purposes only). 

Toggle Kxprcssion trace flag (for debugging purposes only). 

1 A>w, low level debugging aids (type '(??? for help if you are really desperate). 
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Chapter Six 
Coping with Debugger Bugs 

Kraut is still actively being developed and an internal error might show up while you are debugging your 
own program. If the error is an exception defined in "except . dfs", the debugger writes out an 
explanation such as DIVISION BY ZKRO, otherwise the exception is written out as a segment and routine 
number-pair. You have one of the following options: 

• RKCOVKR (Default): Try to return to command level. 

• DKBUG: Recursive debugging mode. You arc prompted for a new window to debug the 
debugger. 

• QUIT: Quit the session. 

The following command is intended for debugging the debugger. 

Verbose 

Set debugging switches interactively. The switches can also be set initially by a file 
M.switchcs, where M is the name of the file containing the main program. 

If you run across an uncaught exception in the debugger, it would be helpful if you could do the following: 

• Recover from the bug. 

• Turn on the switches with the Verbose command. 

• Repeat the command that caused the exception. 

• Enter the recursive debugging mode and print the call stack of the current state of the debugger. 

• Save both transcript files and send them to bob&CS-SPICK (Use the Maintaincr and Report 
commands). 
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Chapter Seven 
Current Restrictions and Known Bugs 

It is not possible to Open modules which are not imported by one of the modules of the program. 

Call chains are not yet implemented ' . 

Consistency checks between source and object files arc not implemented. 

The predicate +TJN1)KT'INK,I) (see page 5) is not implemented. 

The general notation M' ' P] ' . . . ' P n .| ' P n , i denoting variable i in routine P n nested in P n .|,..., 
nested in P|, which is declared in module M has not yet been implemented. Only P'Foo to 
denote the variable Foo in routine P and M' ' P ' Foo to denote the variable Foo in routine P in 
module M arc implemented. 

Because of restrictions in the symbol table, it is not possible to access record fields by name. 
Word (=16 bit) offsets relative to the base address of the record must be used instead. To 
determine word offsets, you have to know how the compiler allocates storage for record fields. 
For example, in the following record definition 

Var Reel 



record 








Rec2: 


record 








i : 
Rec3 


integer; 
: record 








P : 
foo: 
end; 


long; 
tinteger; 




end; 






b: boolean; 






end: 









the field Reel . Rec2 . Rec3 .foot is denoted by the expression Reel. 0.1.2?, where 
Reel . is the offset of field Rec2 in record Reel, etc. Note that the compiler allocates field list 
identifiers separated by commas in the reverse order in which they are mentioned in the 
declaration. For example, in the following definition 

Var Reel : record 

i , j ,k,l ,m, n : integer; 
end; 

the expression Recl.O denotes the field Recl.n and Reel. 4 denotes Recl.k. The above 
examples arc only valid for unpacked records. Ask a compiler hacker if you want to examine 
packed records! 

Array elements are not fully supported: Because there is no symbolic information available for 
the bounds of arrays, the debugger assumes as the lower bound for array variables. Thus for 
arrays starting on a different lower bound, the lower bound has to be normalized to 0. 
Multidimensional arrays are not supported. 



However, one can access allocated but unvisiblc variables by positioning with TopSlack, BoltoniStnck, DownSlack and UpStack 
followed by Locals. 
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• Named Constants (defined with CONST) arc not supported. 

• Display of Records: Records arc displayed on a rather low level. Kraut calls Mack to 
successively interpret each word of the structure as an integer, a long (using two words) , two 
bytes, two characters or the start of a string. The number of words to be displayed can be 
specified or a default value is assumed: For records the number of words necessary to store the 
record and for arrays the size of the subcomponent type. For example, given the program 
fragment 

Var grec : record 

int: integer; 
boo I: boolean; 
end; 

grec. int: = 11111; 
grec. boo! := true; 

grec can be displayed as follows: 

I qrec 

|Record! [TEST3] 

JDisplay how many words? [2]1_ 

| Integer Long LSB MSB Char String[15] 

|TEST3.G172: 11111. 76647. 103. 43. | g +| [103]" +tift/lttft#fftfftRMM n 

The next command (<CR>) can be used to display successive words: 

| <CR> 

|TEST3.G173: 1. 131073. 1. 0. |tAt@| [l]"#" 

|<CR> 

JTEST3.G174: 255. 65791. 255. 0. |XXt@| [255]"#####0##0#f:#R,y# K 

The pair XX is used to indicate a byte which cannot be interpreted as an Ascii character. 

• Because there is no symbolic information for enumerated types, sets arc displayed as bit 
sequences. The leftmost bit refers to the first literal, and the n'th bit from the left to the n'th 
literal of the set. For example, given the program fragment 

type 

color = (red, green, brown, yellow, black, pink) ; 
var 

cset: set of color; 

cset := [red .green, pink]; 

the variable cset will be displayed as 

| cset 

JTEST3.G200: (bits 0..15) 1100010000000000 

• User defined enumerated types must be denoted by their integer equivalent. 

• String search docs not work correctly for files that contain one or more INCLUDE files. 
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Appendix A 
Kraut Command Summary 



Set breakpoint at [after] routine R or line ft. 
Delete breakpoint at routine R or line ft. 
Delete all breakpoints. 



Breakpoints. Page 12 

Break [after] R\# 
DBreak R|# 
DBreak * 

Constant syntax. Page 4 

Any Pascal constant is a valid constant. DHCIMAL Pascal constants in the range -32768.. + 32767 arc of type integer (16 bits), othci"wise 
of type long (32 bits). Constants in a different radix have to be prefixed by a #, a radix indicator (B.D.O.I I) and a size indicator (I.L). 
(B-binary,D=dccmial.O=Octal,H = hexadecimal, I = integer,!. = long). The default radix is 1"), the dcfaultsize I. 



Examples: 



#0L4712347 32 bit octal 

#LHABFD4CD9 32 bit hexadecimal 

#bl0101011 16 bit binary (default: I) 

#bL10101011 32 bit binary 

3434 16 bit decimal 

9896966 32 bit decimal 



Declarations. Page 14 

Counter C ( := I) 
DCounter C 
Define Function F 



Define Counter C and initialize it to (to I) 
Delete Counter C. 
Define path function F. 



Kditor commands. Page 13 

Around (i F) : Show 20 source lines around current line. 

(around line i in file F). 
Grep 'S' (F) : Look for all occurrences of string S. 

starting at current line (starting at line 1 in F) 
Scroll (i F) : Show next 20 source lines from current line 

(from line i in file F). 
(iype) i (j F) : Show source lines i (to j in file F). 
'S'(I) F : Search forward in file F for string S. 

Identifier syntax. Page 4 

Foo Identifier Foo (following Pascal's scope rules) 

Proc'Foo Identifier Foo in routine Proc 

Mod' 'Proc* Foo Identifier Foo in routine Proc in module Mod 
Foo:T Coerce identifier Foo into type T, where T can be 

any type qualifier. 
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Inspect ion commands. Page 17 



& 

Address (ID) 
Compute E 
Current R 



Globals (M) 
Locals (R) 
Parameters 
Radix N 

V( = ) 

VAR:= ID 
Wri te(pl , . . 
Wri teln(pl , 



(R) 



.P'O 



Value of last command. 

Get address of last variable (of ID). 

Compute expression E. 

Move down in the run time stack to R and make it the 

current routine. 

Show all globals of current module (of module M). 

Show all variables of current routine (of routine R). 

Show all parameters of current routine (of routine R). 

Set the current radix to N where N is a DECIMAL (!) 

number in { 2,8,10,16}). Initially the current radix is 10. 

Type the value of V ('=' is needed, if V is also a command) 

Assign the value of ID to VAR . 



,pn): Write the pascal expressions pi pn (and CRLF). 



Line number syntax. 



24 

24 test3 

24 test3.pas;2 

24 sys>accent>test3 



Current line in current source file. 

Line 24 in current file. 

Line 24 in file test3 . pas ; 1 . 

Line 24 in file test3.pas;2. 

Line 24 in file sys>accent>tes t3 . pas ; 1 



Mace. Page 29 

Type MACU to enter the Mace interpreter. Type '? to Mace for further help. Mace commands can also be typed to Kraut; Type SM to 
the Kraut interpreter to execute the mace command M. 



Miscellaneous. Page 21 

QFILE.kmd 
$M 

Current M 
Exception 
Expert (0N|0FF) 
Indent N 
Shell 



Execute default command file (FILE. kind). 

Execute Mace command M. 

Start of a comment. 

Set current module to M (same as OPEN M). 

Show the current exception. 

Expert switch. (Default: OFF). 

Concatenate N blanks with the prompt sign. 

Create another shell with current environment, 



Model commands. Page 26 

(Model) Bargraph B MX S 

(Model ) Routine M R 
Bind ID M 
DModel M 
DBind ID 



Define (or rescale) bargraph B with maximum 

value MX and scale S (Linear or Log). 

Define a model M and bind the routine R to it. 

Bind variable It) to model M. 

Delete model M. 

Delete ID'S binding to a model. 



Next command. Page 18 



<CR> 



Execute the previous command with new arguments. 
Implemented for $, Around, Calls, DownStack, Search, 
SingleStep, Type, UpStack. 
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Pathrule Commands. Page 14 

ITic following commands arc defined for palh rules. If only the name R of the path rule is typed, you are prompted for the missing 
arguments: 



Action R A 

CheckPath R G 

Disable R 

EditPathRule R 

Enable R 

FindPath R G 

PathRules ( active| inactive) 

PathRules verbose 

Remove (Action) R 



Bind action A to path rule R. 

Qua! ify G as a CHECK path rule with name R 

Enable path rule with name R. 

Edit path rule R. 

Disable path rule with name R. 

Qualify G as a FIND path rule with name R. 

Show (active or inactive) path rules. 

Verbose while interpreting path actions. 

Delete path rule R (or action only). 



Reporting bugs. 

Maintainer (M) 
News 



Report A6M 



Script ON|OFF 
Verbose 
vers ion 



Get name of maintainer of all modules (of module M). 
Print any news about new features, known bugs, etc that 

are not undocumented in the Spice manual. 
When QUITting the debugger, the script file will be 
given to the Spice Mail system to mail it to address A at 
machine M. 

Set transcript switch ON or OFF (default: ON). 
Set various debugging switches (For internal debugging). 
Get the current version of KRAUT. 



Runtimcstack commands. Page 18 



BottomStack 
Calls (#) 
DownStack (If) 
TopStack 
Unwind 
UpStack (if) 



Move to bottom of stack. 

Show current call sequence(// levels). 

Move backward 1 (//) routine(s) in dynamic call chain. 

Move to top of stack. 

Remove last EXECUTED routine from stack. 

Move forward 1 (#) routine(s) in dynamic call chain. 



Show command. 



Show P 

P 
P 
P 
P 



P = 



P can be one of the following values: 



Breaks 
Counters 
Models 
Modules 



Pathfunctions M: 
PathRules PI 



P = Routines M 



Runfile R M 



Show the current break point 
Show the currently defined co 
Show the current models. 
If M is omitted, then type KR 
Otherwise give some informal i 
This includes date of compila 
qmap and sym files, names of 
Show the user defined path fu 
If M is omitted, show them fo 
If Pl='active', then display 
pathrules. if Pl= ' inactive' , 
of disabled path rules, other 
defined path rules. 
Show the routines and user de 
for module M. If M is omitted 
all modules. 
Dump the contents of run file 



list. 

unter variables. 

AUT' s module 1 ist. 
on about module M. 
tion, names of seg, 
imports, etc. 
notions for module M. 
r all modules, 
the list of enabled 
then display the list 
display all currently 

fined path functions 
then show them for 

R into file M. 
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P = Search! ist 
P = Windows 



Display Accent's file search list. 
Display the currently defined windows 



Searchlist commands. Page 10 



ChDir D 

Close M 
Open M 
SetSearch L 
System 



: Set current directory to D. If D is missing, 
show current directory. 
Close module M ( * for all modules). 
Open module M ( * for all modules). 
Modify file search list : - (pop), ID (push) 
Open Pascal Init and all its imports. 



Target Process commands. Page 19 

If ihc largct process is RUNNING, the following commands and control characters can be typed. Note that control characters have to 
be typed in the window of the debugger, not that of the target process: 



tDEL t 

tDEL c, tDEL k, tDEL d 
Halt 



: Show the state of the target process 

(Not yet implemented) 
: Return to command level. 
: Suspend execution of target process. 



If the largct process has STOPPL-D the following commands can be executed: 



P(pl,...pn). 
Execute P(pl, . . .pn) 



Go 

Run (A) 

TorminateTarget YES|N0 



Execute routine R with parameters pl,...,pn. R can 

also be the main program. Omit closing ')' for 

parameter check. 

Resume execution of target process. 

Start execution of target process (with arguments A) 

Do or do not terminate target process on QUIT. 



Trace commands. Page 1 1 

Trace [Before |After] R [C] : Trace routine R (only its entry or exit) 

and perform commands C. If R is a module 
set traces for all of the routines of R. 



DTrace [Before] After] R 



: Delete trace of R (only entry or exit). 
If R is a module, delete all traces for 
module R. 



ypc qualifier. Page 4 



Array[n] 

Boolean 

Char 

'Integer 

Long 



array (n words) 

byte (8 bit) 

char 

integer (16 bit) 

long (32 bit) 



Pointer 

Record[n] 

REal 

String 

SEt[n] 



pointer 

record (n words) 

real 

string 

set (n words) 
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Window commands. Page 25 

Window W LX TY W H : Create window W with tipper left corner LX.TY and 

W characters per line and II lines. 
Window W : Move to W if it exists, otherwise create window 

with default coordinates. 
DWindow W : Delete window W. 

DWindow * : Delete all existing debug windows except for the 

current one. 
C >> W : Redirect output for command C into window W. 

Window W is created with default coordinates, 

if it does not yet exist. 
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